/**
 * Copyright (c) 2006-2012 Las Venturas Playground, LVP Mineground
 *
 * This program is free software: you can redistribute it and/or modify it under the terms of the
 * GNU General Public License as published by the Free Software Foundation, either version 3 of the
 * License, or (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without
 * even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 * General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License along with this program.
 * If not, see <http://www.gnu.org/licenses/>.
 */

package mineground.core;

/**
 * The Base class for Module Controllers contains shared and critical knowledge required for them
 * to work properly. Besides some internal logic, it exposes a few behavioral methods:
 * 
 * ** void unregister()
 * 
 *    When a module sees reason to remove itself from the game logic, it can call the unregister
 *    method. This will cause it to be unregistered with the module registry, thus also removing
 *    any registered handlers. This is equal to shutting down the class.
 * 
 * There also are methods available which will be called by other internal systems, which may be
 * overridden by modules to get more control over what happens during certain events.
 * 
 * ** void onDispose()
 * 
 *    This method will be invoked when the module is about to be shut down. Overriding it allows
 *    a module to define their own on shut-down logic, acting as a destructor.
 * 
 * Various systems dealing with modules will use this class as their primary interface, as the
 * rest of the implementation and architecture is completely up to the module itself.
 */
public class ModuleControllerBase {
    /**
     * The active instance of the module registry.
     */
    private static ModuleRegistry mModuleRegistry;
    
    /**
     * The active instance of the Message Loop, which can be used to transmit messages and tasks
     * to other threads.
     */
    protected static MessageLoop mMessageLoop;
    
    /**
     * Update the module registry instance which is in use right now. This instance will be used
     * to unregister the module when it requests this itself.
     * 
     * @param moduleRegistry The Module Registry which owns all modules.
     */
    public static void setModuleRegistry(ModuleRegistry moduleRegistry) {
        mModuleRegistry = moduleRegistry;
    }
    
    /**
     * Set the active instance of the message loop which can be used for all module instances. This
     * should be called once during initialisation.
     * 
     * @param messageLoop The Message Loop for the Mineground instance.
     */
    public static void setMessageLoop(MessageLoop messageLoop) {
        mMessageLoop = messageLoop;
    }
    
    /**
     * Invoking the unregister method may only be done by the controller itself, and will remove it
     * from the Module Registry. All registered message handlers will be removed, causing the
     * module to be shut down. The onDispose() method will be invoked on the current thread.
     */
    protected void unregister() {
        if (mModuleRegistry == null)
            return;
        
        // Unregister the Module with the Module Registry, and remove it.
        mModuleRegistry.unregister(this, true);
    }
    
    /**
     * Provide an empty implementation of the onDispose method. This will be called by the Module
     * Registry just before it's getting disposed of, allowing the module to cleanly shut down any
     * owned logic or services.
     */
    public void onDispose() { }
}